Atom AI Labs - AI-Powered Multi-Tenant Platform

Public Marketplace API Documentation

The ATOM Public Marketplace API provides programmatic access to browse, search, and discover AI skills from the ATOM ecosystem. This API enables developers to build integrations, tools, and applications that leverage the growing catalog of community-contributed AI capabilities.

Quick Start
Authentication
Rate Limiting
API Reference
Error Handling
Code Examples
Best Practices
Changelog

---

Quick Start

Base URL

https://api.atomagentos.com/api/public/v1

Browse All Skills

curl -X GET "https://api.atomagentos.com/api/public/v1/marketplace/skills"

**Response:**

{
  "skills": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "Data Extractor",
      "slug": "data-extractor",
      "description": "Extract structured data from unstructured text",
      "category": "data-processing",
      "tags": ["extraction", "nlp", "automation"],
      "type": "api",
      "price": 0.0,
      "is_free": true,
      "rating": 4.5,
      "rating_count": 23,
      "installs": 1500
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0,
  "has_more": false
}

---

Authentication

The Public Marketplace API has two authentication tiers:

1. Public Access (Read-Only)

No authentication required for browsing and searching skills. Simply make requests to the public endpoints.

**Headers:** None required

2. Authenticated Access (Write Operations)

Required for:

Submitting skills to the marketplace
Rating and reviewing skills
Installing skills (via authenticated endpoints)

API Key Authentication

curl -X POST "https://api.atomagentos.com/api/public/v1/marketplace/submit" \
  -H "X-API-Key: atom_pub_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Skill",
    "description": "A useful skill",
    ...
  }'

OAuth 2.0 Bearer Token

curl -X POST "https://api.atomagentos.com/api/public/v1/marketplace/submit" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{...}'

---

Rate Limiting

Rate limits are enforced based on authentication method:

Unauthenticated Requests

**60 requests per minute**
**1,000 requests per day**

Authenticated Requests (API Key)

**300 requests per minute**
**10,000 requests per day**

Authenticated Requests (OAuth)

**600 requests per minute**
**50,000 requests per day**

Rate Limit Headers

Every response includes rate limit information:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1708412800

Exceeding Limits

When you exceed the rate limit, you'll receive a 429 Too Many Requests response:

{
  "success": false,
  "error": {
    "message": "Rate limit exceeded",
    "code": "RATE_LIMIT_EXCEEDED",
    "details": {
      "retry_after": 45
    }
  }
}

---

API Reference

Browse Skills

Browse and filter the marketplace catalog.

**Endpoint:** GET /marketplace/skills

**Parameters:**

Parameter	Type	Required	Description
`query`	string	No	Search in skill name and description
`category`	string	No	Filter by category
`tags`	string	No	Filter by tags (comma-separated)
`type`	string	No	Filter by skill type (`api`, `function`, `script`, `docker`, `container`)
`is_free`	boolean	No	Filter for free skills only (`true`)
`is_featured`	boolean	No	Filter for featured skills only (`true`)
`sort_by`	string	No	Sort field (`created_at`, `name`, `rating`, `installs`). Default: `created_at`
`sort_order`	string	No	Sort order (`asc`, `desc`). Default: `desc`
`limit`	integer	No	Page size (1-100). Default: `50`
`offset`	integer	No	Page offset. Default: `0`

**Example:**

curl -X GET "https://api.atomagentos.com/api/public/v1/marketplace/skills?category=data-processing&type=api&sort_by=rating&sort_order=desc&limit=10"

**Response:**

{
  "skills": [
    {
      "id": "uuid",
      "name": "Skill Name",
      "slug": "skill-name",
      "description": "Short description",
      "long_description": "Detailed markdown description",
      "category": "category-name",
      "tags": ["tag1", "tag2"],
      "version": "1.0.0",
      "type": "api",
      "price": 0.0,
      "is_free": true,
      "is_featured": false,
      "installs": 100,
      "rating": 4.5,
      "rating_count": 20,
      "success_rate": 0.95,
      "license": "MIT",
      "author_tenant_id": "tenant-uuid",
      "documentation_url": "https://docs.example.com",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 150,
  "limit": 10,
  "offset": 0,
  "has_more": true
}

---

Get Skill Details

Retrieve detailed information about a specific skill.

**Endpoint:** GET /marketplace/skills/{skill_id}

**Parameters:**

Parameter	Type	Required	Description
`skill_id`	string	Yes	Skill UUID

**Example:**

curl -X GET "https://api.atomagentos.com/api/public/v1/marketplace/skills/123e4567-e89b-12d3-a456-426614174000"

**Response:**

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Data Extractor",
  "slug": "data-extractor",
  "description": "Extract structured data from unstructured text",
  "long_description": "# Data Extractor\n\nThis skill uses advanced NLP...",
  "category": "data-processing",
  "tags": ["extraction", "nlp", "automation"],
  "version": "2.1.0",
  "type": "api",
  "price": 0.0,
  "is_free": true,
  "is_featured": true,
  "installs": 1500,
  "rating": 4.5,
  "rating_count": 23,
  "success_rate": 0.98,
  "license": "MIT",
  "author_tenant_id": "tenant-uuid",
  "documentation_url": "https://docs.example.com/data-extractor",
  "repository_url": "https://github.com/example/data-extractor",
  "created_at": "2024-01-15T00:00:00Z",
  "updated_at": "2024-02-01T00:00:00Z"
}

---

Get Categories

List all skill categories in the marketplace.

**Endpoint:** GET /marketplace/categories

**Example:**

curl -X GET "https://api.atomagentos.com/api/public/v1/marketplace/categories"

**Response:**

{
  "categories": [
    "data-processing",
    "communication",
    "automation",
    "analytics",
    "integration"
  ]
}

---

Get Tags

List all tags with usage counts.

**Endpoint:** GET /marketplace/tags

**Parameters:**

Parameter	Type	Required	Description
`limit`	integer	No	Maximum tags to return (default: 50)

**Example:**

curl -X GET "https://api.atomagentos.com/api/public/v1/marketplace/tags?limit=20"

**Response:**

{
  "tags": [
    {"name": "automation", "count": 45},
    {"name": "nlp", "count": 32},
    {"name": "integration", "count": 28},
    {"name": "analytics", "count": 21}
  ]
}

---

Submit Skill (Authenticated)

Submit a new skill to the marketplace for review.

**Endpoint:** POST /marketplace/submit

**Authentication:** Required (API Key or OAuth)

**Request Body:**

{
  "name": "My Skill",
  "description": "A brief description",
  "long_description": "Detailed markdown documentation",
  "type": "api",
  "category": "data-processing",
  "tags": ["automation", "nlp"],
  "price": 0.0,
  "license": "MIT",
  "documentation_url": "https://docs.example.com",
  "repository_url": "https://github.com/example/my-skill",
  "input_schema": {
    "type": "object",
    "properties": {
      "text": {"type": "string"}
    }
  },
  "output_schema": {
    "type": "object",
    "properties": {
      "result": {"type": "string"}
    }
  },
  "config": {},
  "code": "def execute(input): return {'result': input['text']}"
}

**Example:**

curl -X POST "https://api.atomagentos.com/api/public/v1/marketplace/submit" \
  -H "X-API-Key: atom_pub_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d @skill.json

**Response:**

{
  "id": "new-skill-uuid",
  "name": "My Skill",
  "status": "pending_approval",
  "submitted_at": "2024-02-19T00:00:00Z"
}

---

Rate Skill (Authenticated)

Rate and review a skill.

**Endpoint:** POST /marketplace/skills/{skill_id}/rate

**Authentication:** Required (API Key or OAuth)

**Request Body:**

{
  "rating": 5,
  "review": "Excellent skill! Very useful for automation."
}

**Parameters:**

Field	Type	Required	Description
`rating`	integer	Yes	Rating from 1 to 5
`review`	string	No	Optional review text

**Example:**

curl -X POST "https://api.atomagentos.com/api/public/v1/marketplace/skills/123e4567-e89b-12d3-a456-426614174000/rate" \
  -H "X-API-Key: atom_pub_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"rating": 5, "review": "Great!"}'

**Response:**

{
  "success": true,
  "rating": 5
}

---

Get Skill Reviews

Get reviews for a specific skill.

**Endpoint:** GET /marketplace/skills/{skill_id}/reviews

**Parameters:**

Parameter	Type	Required	Description
`skill_id`	string	Yes	Skill UUID
`limit`	integer	No	Page size (default: 20)
`offset`	integer	No	Page offset (default: 0)

**Example:**

curl -X GET "https://api.atomagentos.com/api/public/v1/marketplace/skills/123e4567-e89b-12d3-a456-426614174000/reviews?limit=10"

**Response:**

{
  "reviews": [
    {
      "id": "review-uuid",
      "rating": 5,
      "review": "Excellent skill!",
      "created_at": "2024-02-01T00:00:00Z"
    }
  ],
  "total": 23,
  "limit": 10,
  "offset": 0
}

---

Error Handling

The API uses standard HTTP status codes and returns detailed error messages.

HTTP Status Codes

Code	Description
`200 OK`	Request successful
`400 Bad Request`	Invalid request parameters
`401 Unauthorized`	Missing or invalid authentication
`403 Forbidden`	Insufficient permissions
`404 Not Found`	Resource not found
`429 Too Many Requests`	Rate limit exceeded
`500 Internal Server Error`	Server error

Error Response Format

{
  "success": false,
  "error": {
    "message": "Human-readable error message",
    "code": "ERROR_CODE",
    "details": {}
  }
}

Common Error Codes

Code	Description
`INVALID_API_KEY`	The provided API key is invalid or revoked
`RATE_LIMIT_EXCEEDED`	Rate limit has been exceeded
`SKILL_NOT_FOUND`	The requested skill does not exist
`INVALID_PARAMETER`	A request parameter is invalid
`DATABASE_ERROR`	A database error occurred
`AUTHENTICATION_REQUIRED`	Authentication is required for this endpoint

---

Code Examples

JavaScript / Node.js

Browse Skills

async function browseSkills() {
  const response = await fetch(
    'https://api.atomagentos.com/api/public/v1/marketplace/skills?' +
    new URLSearchParams({
      category: 'data-processing',
      type: 'api',
      sort_by: 'rating',
      limit: 10
    })
  );

  const data = await response.json();
  console.log(`Found ${data.total} skills:`);
  data.skills.forEach(skill => {
    console.log(`- ${skill.name} (Rating: ${skill.rating})`);
  });
}

browseSkills();

Submit Skill with API Key

async function submitSkill(apiKey, skillData) {
  const response = await fetch(
    'https://api.atomagentos.com/api/public/v1/marketplace/submit',
    {
      method: 'POST',
      headers: {
        'X-API-Key': apiKey,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(skillData)
    }
  );

  const result = await response.json();
  if (result.error) {
    console.error('Submission failed:', result.error);
  } else {
    console.log('Skill submitted:', result.id);
  }
}

const skillData = {
  name: 'My Skill',
  description: 'A useful skill',
  type: 'api',
  category: 'automation',
  tags: ['automation'],
  input_schema: { type: 'object', properties: {} },
  output_schema: { type: 'object', properties: {} }
};

submitSkill('atom_pub_YOUR_KEY_HERE', skillData);

Python

Browse Skills

import requests

def browse_skills():
    url = "https://api.atomagentos.com/api/public/v1/marketplace/skills"
    params = {
        "category": "data-processing",
        "type": "api",
        "sort_by": "rating",
        "limit": 10
    }

    response = requests.get(url, params=params)
    data = response.json()

    print(f"Found {data['total']} skills:")
    for skill in data['skills']:
        print(f"- {skill['name']} (Rating: {skill['rating']})")

browse_skills()

Submit Skill with API Key

import requests

def submit_skill(api_key, skill_data):
    url = "https://api.atomagentos.com/api/public/v1/marketplace/submit"
    headers = {
        "X-API-Key": api_key,
        "Content-Type": "application/json"
    }

    response = requests.post(url, json=skill_data, headers=headers)
    result = response.json()

    if 'error' in result:
        print(f"Submission failed: {result['error']}")
    else:
        print(f"Skill submitted: {result['id']}")

skill_data = {
    "name": "My Skill",
    "description": "A useful skill",
    "type": "api",
    "category": "automation",
    "tags": ["automation"],
    "input_schema": {"type": "object", "properties": {}},
    "output_schema": {"type": "object", "properties": {}}
}

submit_skill('atom_pub_YOUR_KEY_HERE', skill_data)

---

Best Practices

1. Pagination

Always use pagination for large result sets:

# First page
curl "/marketplace/skills?limit=50&offset=0"

# Second page
curl "/marketplace/skills?limit=50&offset=50"

Check has_more in the response to determine if there are more results.

2. Caching

Cache category and tag lists as they change infrequently:

# Cache this for 1 hour
curl "/marketplace/categories"

3. Search Optimization

Use specific filters for better performance:

# Good - Specific search
curl "/marketplace/skills?category=data-processing&type=api"

# Less efficient - Broad search
curl "/marketplace/skills?query=data"

4. Error Handling

Always handle errors gracefully:

try {
  const response = await fetch(url);
  const data = await response.json();

  if (!response.ok || data.error) {
    console.error('API Error:', data.error);
    return;
  }

  // Process data
} catch (error) {
  console.error('Network error:', error);
}

5. Rate Limiting

Monitor rate limit headers and implement backoff:

const response = await fetch(url);
const remaining = response.headers.get('X-RateLimit-Remaining');

if (remaining < 10) {
  console.warn('Approaching rate limit');
}

6. Authentication Security

Never expose API keys in client-side code
Use OAuth tokens for user-specific operations
Rotate API keys regularly
Store keys in environment variables

---

Changelog

Version 1.0.0 (2024-02-19)

Initial public release
Browse skills endpoint
Category and tag endpoints
Skill submission API
Rating and review system
API key and OAuth authentication

---

Support

**Documentation:** https://atomagentos.com/docs/marketplace
**API Status:** https://atomagentos.com/status
**GitHub Issues:** https://github.com/atom-platform/marketplace-api/issues
**Email:** api-support@atomagentos.com

---

License

The Public Marketplace API is provided under the MIT License. See https://atomagentos.com/license for details.

Public Marketplace API Documentation

Table of Contents

Quick Start

Base URL

Browse All Skills

Authentication

1. Public Access (Read-Only)

2. Authenticated Access (Write Operations)

API Key Authentication

OAuth 2.0 Bearer Token

Rate Limiting

Unauthenticated Requests

Authenticated Requests (API Key)

Authenticated Requests (OAuth)

Rate Limit Headers

Exceeding Limits

API Reference

Browse Skills

Get Skill Details

Get Categories

Get Tags

Submit Skill (Authenticated)

Rate Skill (Authenticated)

Get Skill Reviews

Error Handling

HTTP Status Codes

Error Response Format

Common Error Codes

Code Examples

JavaScript / Node.js

Browse Skills

Submit Skill with API Key

Python

Browse Skills

Submit Skill with API Key

Best Practices

1. Pagination

2. Caching

3. Search Optimization

4. Error Handling

5. Rate Limiting

6. Authentication Security

Changelog

Version 1.0.0 (2024-02-19)

Support

License